Web SDK

Añade AR Clip VPS a tu propia página web. El Web SDK encuentra, directamente en el navegador, dónde está el visitante en tus mapas VPS, sin instalar ninguna app.

Antes de empezar

Una clave de API. Escríbenos a través de Soporte para conseguirla.
Los ID de ubicación de tus mapas. Cada mapa tiene uno: consulta la Introducción.
Una página servida por HTTPS. Los navegadores solo dan acceso a la cámara y a los sensores de movimiento a las páginas seguras. localhost también cuenta como seguro.

Instalación

npm install @web-ar-studio/webar-engine-sdk

El paquete está en npm e incluye sus tipos de TypeScript.

Iniciar VPS

VPS funciona dentro de una sesión de seguimiento del mundo. Añade vps a init() y escribe en él tus ID de ubicación. El SDK no dibuja nada por sí mismo: muestra la escena con el motor que prefieras, ya sea three.js, Babylon.js, PlayCanvas o WebGL puro.

import * as THREE from "three";
import WAS, {
  PROJECT_MODE_SLAM,
  TRIGGER_MODE_SLAM,
  CAMERA_MODE_ENVIRONMENT,
  PROVIDER_8THWALL,
  EVENT_FRAME,
  EVENT_VPS_READY,
  EVENT_VPS_LOCALIZED,
  EVENT_VPS_NOT_LOCALIZED,
  EVENT_VPS_ERROR,
} from "@web-ar-studio/webar-engine-sdk";

const was = new WAS();

const { canvas, context } = await was.init({
  apiKey: "your-api-key",
  mode: PROJECT_MODE_SLAM,
  cameraMode: CAMERA_MODE_ENVIRONMENT,
  container: document.querySelector("#ar"),
  triggers: [{ id: 1, mode: TRIGGER_MODE_SLAM, source: null }],
  vps: { locationIds: ["your-location-id"] },
});

const renderer = new THREE.WebGLRenderer({ canvas, context });

was.on(EVENT_VPS_READY, () => console.log("VPS started"));
was.on(EVENT_VPS_LOCALIZED, ({ locationId, offset }) => {
  console.log("Found the place on map", locationId, offset);
});
was.on(EVENT_VPS_NOT_LOCALIZED, ({ status, statusDescription }) => {
  console.log("Not found yet:", status, statusDescription);
});
was.on(EVENT_VPS_ERROR, (message) => console.warn("VPS error:", message));

// El seguimiento y VPS arrancan con el callback de fotograma. Regístralo con un toque:
// WebXR y los sensores de movimiento del iPhone necesitan un gesto del usuario.
startButton.onclick = () =>
  was.on(EVENT_FRAME, () => renderer.render(scene, camera));

Si no pones locationIds, VPS localiza de forma global, sin apuntar a un mapa concreto. Tarda más, así que sube requestTimeoutMs.

Pasa vps a init()

En Chrome para Android, el acceso a la cámara para VPS solo se concede al iniciar la sesión. Si empiezas sin vps, ya no podrás activar VPS en esa sesión: setupVPS() lanza VpsError.

Dónde funciona

El SDK elige un motor de seguimiento (provider) en el dispositivo. Con el valor por defecto "auto", prueba primero webxr y después 8thwall.

Motor	Dónde	VPS
`webxr`	Chrome en Android	Sí. El SDK coloca la escena en el mapa por sí mismo.
`8thwall`	Navegadores sin WebXR, como Safari en iPhone	Sí. Aplicas `offset` tú mismo.
`arclip-webar`	Solo si lo eliges expresamente	No

Contenido en el mapa

Coloca tu contenido en las coordenadas de tu mapa VPS. Cuando VPS encuentra el lugar, EVENT_VPS_LOCALIZED te da offset: el desplazamiento que lleva el mundo del seguimiento al mapa.

En webxr, el SDK ya ha aplicado offset de forma suave, así que el contenido del mapa aparece en su sitio.
En 8thwall, el SDK solo te informa de offset. Pon el contenido del mapa en un grupo y dale al grupo la inversa de offset en cada localización:

const mapRoot = new THREE.Group(); // todo lo colocado en coordenadas del mapa
scene.add(mapRoot);

was.on(EVENT_VPS_LOCALIZED, ({ offset }) => {
  if (was.getActiveProviderId() !== PROVIDER_8THWALL) return; // webxr lo aplica por sí mismo
  const { position: p, orientation: q } = offset;
  new THREE.Matrix4()
    .compose(
      new THREE.Vector3(p.x, p.y, p.z),
      new THREE.Quaternion(q.x, q.y, q.z, q.w),
      new THREE.Vector3(1, 1, 1),
    )
    .invert()
    .decompose(mapRoot.position, mapRoot.quaternion, mapRoot.scale);
});

El SDK acepta un resultado solo si la coincidencia es lo bastante fiable y si el salto desde el resultado anterior se puede recorrer a pie. Todo lo demás llega como EVENT_VPS_NOT_LOCALIZED. Así el contenido no salta en lugares que se parecen, como los pasillos largos.

Eventos

Evento	Qué recibes
`EVENT_VPS_READY`	Nada. VPS ha arrancado.
`EVENT_VPS_LOCALIZED`	`locationId`, `offset` (`position`, `orientation`), `trackingPosition`, `trackingRotation`, `vpsPosition`, `vpsRotation`, `timestamp`
`EVENT_VPS_NOT_LOCALIZED`	`status`, `statusDescription`, `failCount`
`EVENT_VPS_ERROR`	Un mensaje de error, como cadena

Controlar VPS

Método	Qué hace
`startVPS()`, `stopVPS()`	Reanuda o pausa la localización
`isVPSActive()`	Indica si VPS está en marcha
`setVPSLocationIds(ids)`	Cambia a otros mapas; con una lista vacía localiza de forma global
`setupVPS(config)`	Cambia los ajustes de VPS durante una sesión
`updateVPSSession()`	Inicia una sesión de VPS nueva, para que los resultados anteriores ya no influyan en los nuevos
`resetTracking()`	Descarta la corrección de VPS y empieza de nuevo, por ejemplo tras un resultado erróneo

Ajustes

Todos los campos de vps son opcionales. El SDK toma apiKey de init(), así que no hace falta repetirlo.

Campo	Por defecto	Qué hace
`locationIds`	ninguno	Los mapas con los que se compara la imagen de la cámara. Sin él, VPS localiza de forma global.
`captureInterval`	`2500`	Tiempo entre peticiones de localización, en ms
`requestTimeoutMs`	`20000`	Cuánto esperar una respuesta, en ms
`maxFailsCount`	`5`	Fallos seguidos tras los que el SDK inicia una sesión de VPS nueva
`imageFormat`	`"jpeg"`	`"jpeg"` o `"webp"`. Usa WebP solo con un servidor que lo lea. Si el navegador no sabe codificar WebP, el SDK envía JPEG.
`jpegQuality`	`1`	Calidad de la imagen, de 0 a 1
`targetWidth`, `targetHeight`	`540`, `960`	Tamaño del fotograma que se envía al servidor
`minInlierRatio`, `minNumInliers`	`0.6`, `600`	Lo fiable que debe ser una coincidencia para aceptarla
`maxJumpBaseMeters`, `maxJumpSpeedMps`	`3`, `2`	Cuánto puede alejarse un resultado nuevo del anterior: `maxJumpBaseMeters` más `maxJumpSpeedMps` por cada segundo desde el último resultado
`serverUrl`	AR Clip VPS	Otro servidor de VPS
`sendApiKeyHeader`	`true`	Envía la clave en la cabecera `x-vps-apikey`. Desactívalo solo para tu propio servidor, si no acepta esta cabecera.

Errores

Si VPS no puede funcionar en esta sesión, init() o un método de VPS falla con un error llamado VpsError (constante VPS_ERROR). Los errores posteriores al arranque, como una petición fallida, llegan en EVENT_VPS_ERROR.

Más

El README del paquete describe los demás modos de seguimiento, las anclas y la configuración completa con three.js.
Para configurar VPS sin código, usa las Escenas VPS en AR Clip Studio.

Siguiente: Dispositivos compatibles — teléfonos, navegadores y visores.

Antes de empezar​

Instalación​

Iniciar VPS​

Dónde funciona​

Contenido en el mapa​

Eventos​

Controlar VPS​

Ajustes​

Errores​

Más​